home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 3 / BBS in a box - Trilogy III.iso / Files / Prog / D-G / File Dropper 1.1b3 / Read Me - File Dropper < prev   
Encoding:
Text File  |  1993-08-29  |  12.7 KB  |  275 lines  |  [TEXT/KAHL]
  1.                                     File Dropper 1.1ß3
  2.                                     Written by Troy Anderson
  3.  
  4.                     Copyright © 1992-1993, Troy Anderson; All Rights Reserved
  5.  
  6.                                     What Is This Thing?
  7.  
  8. File Dropper is a THINK C library that implements an application that you can drop files or 
  9. folders onto to do batch operations on.  It handles the getting of the AppleEvents if 
  10. running under System 7, the main event loop, and the menus.  You need only write the code 
  11. that acts on the individual files.
  12.  
  13.  
  14.                                     New Features in 1.1ß3
  15.                                     
  16. • Fixed a bug so that when you drop a folder onto your File Dropper application, all the files
  17.   inside are processed in stead of just the first one.
  18.   
  19.  
  20.                                     New Features in 1.1ß2
  21.                                     
  22. • Built "File Dropper π" in THINK C 6.0
  23. • The cursor is NOT reset to an arrow after each call to SetStatusPercentage.
  24. • If you return FALSE from the eStartup, eSFInitialize, or eAEInitialize messages, File Dropper 
  25.   will send you an eQuitting message and quit the application.
  26. • If you return FALSE from the eValidate message, File Dropper will skip any remaining files
  27.   in the current batch.
  28. • If you return FALSE from an eDispose message, File Dropper will send you an eQuitting message
  29.   and quit the application.  Returning TRUE from an eDispose message will cause File Dropper to
  30.   continue running.  This behavior does NOT depend upon which of eSFInitialize or eAEInitialize
  31.   was sent to you.
  32. • If you return TRUE from an eQuitting message, the File Dropper quits.  On the other hand, if 
  33.   you return FALSE from an eQuitting message, File Dropper will quit.
  34. • If you want the source code to File Dropper, send me money (see the end of this document).
  35. • Added an eUserCancelled message for when the user clicks Cancel in the status box.
  36. • Added an eIdle message.
  37. • Added the ChangeStatusMessage function that lets you change the message in the status dialog
  38.   on the fly, during your processing of the file.
  39. • Changed some things internally, so you can NOT call InstallCustomGetFSSpecFunc,
  40.   InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc from an eSFInitialize or 
  41.   eAEInitialize message any more, just from eStartup.
  42. • Fixed a bug in the ErrorAlert function so that text relating to the error as well as the
  43.   word "Error." show up in the dialog.
  44. • Made it simpler to support AboutBox functionality.  You just put text in STR# resource 129, and
  45.   it will be displayed in the warp stars.  To enable this feature, return TRUE from the 
  46.   eDoAboutBox message.
  47.                                     
  48.                                     
  49.                                     New Features in 1.1ß1
  50.                                     
  51. • Now you can specify if you want the status dialog displayed while you are working on the files,
  52.   wether they were selected with SFGetFile or an AppleEvent.
  53. • There is a progress bar like Finder 7's that you update by specifying how far along you are with
  54.   a percentage (0 - 100).  You can elect to turn this option off, too.
  55.  
  56.     
  57.                                     How Do I Implement My Part?
  58.  
  59. All definitions and prototypes that you need are in the "FD Interface.h" file.  You simply write
  60. the ModuleMain function, and let the library do the rest.
  61.  
  62. The ModuleMain function takes two parameters, a short and a ModuleDataRec.  The short is a 
  63. message that tells you why you were called.  The ModuleDataRec is a record that contains data 
  64. that you may need in order to perform the required task.  It returns a Boolean value.  The
  65. returned value is ignored in all but one case, when you are sent an eValidateFile message.  See
  66. the eValidateFile message description below for details.
  67.  
  68. Be sure that all of the resources in "File Dropper Starter π.rsrc" are included in the resource
  69. file for your project.  It's easiest to make a copy of "File Dropper Starter π.rsrc" and use it.
  70.  
  71. To allow dropping of different types of files/folders/volumes onto your application, change the
  72. 'FREF' resource to include the types of files you can act on.  There are some special types that
  73. correspond to folders, volumes, etc.  For a more indepth discussion of this, see section 9-17 
  74. of Inside Macintosh Volume VI.  See section 9-30 for a list of file types you can use for folders,
  75. floppy disks, the trash, etc.
  76.  
  77. Be sure to change the creator type in the Set Project Type… menu of THINK C, and the creator 
  78. type in the resource file, and to give your application a cool icon.
  79.  
  80.                                     What Is A ModuleDataRec?
  81.  
  82. The ModuleDataRec is defined as follows:
  83.  
  84. typedef struct {
  85.     FSSpec    *theFile;        // a file specification
  86.     long    refcon;            // a reference constant for you to do with what you will
  87.     } ModuleDataRec;
  88.  
  89.                                     What Are The Messages?
  90.                                     
  91. There are 6 possible messages, they are eStartup, eAEInitialize, eSFInitialize, 
  92. eValidateFile, eProcessFile, eDispose, and eQuitting.
  93.  
  94. You get the messages in this order:
  95.  
  96. eStartup
  97.     This tells you that the program just started up.  You get this message exactly once.
  98.     In the ModuleDataRec, theFile and refcon are initialize to NULL and 0 respectively.  You
  99.     are free to use refcon for anything you choose, including allocating a handle and saving
  100.     its value in refcon so you can have additional storage.  Nothing really precludes you from
  101.     having global data hanging around, but someday this thing may evolve into a CODE resource
  102.     interface that will make having globals more difficult. I never touch refcon, so what you
  103.     do with it is up to you.
  104.     
  105.     This is a where you should call the customization routines like SetStatusParams,
  106.     InstallCustomGetFSSpecFunc,    InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc.
  107.     Although it's all right to call SetStatusParams from eAEInitialize or eSFInitialize as well.
  108.     
  109.     Return TRUE if everything you did turned out OK (e.g. you got all the memory you asked for).
  110.     Returning FALSE causes File Dropper to send you an eQuitting message and quit.
  111.     
  112. eAEInitialize or eSFInitialize
  113.     This tells you that a file/folder/volume has been selected by the user to be acted upon.
  114.  
  115.     eAEInitialize indicates that the file/folder/volume was "dropped" onto the application or
  116.     sent to it using an 'odoc' AppleEvent.
  117.  
  118.     eSFInitialize indicates that the file (of folder or volume if you've installed a Custom
  119.     GetFSSpec Function using InstallCustomGetFSSpecFunction()) was selected by the user using
  120.     a standard get file dialog.  NOTE: You get this message AFTER the user selects the file.
  121.     If you want to install a custom get file using InstallCustomGetFSSpecFunc,
  122.     InstallCustomFileFilterFunc, or InstallCustomDialogHookFunc, do it in eStartup, not here.
  123.  
  124.     
  125.     It is handy to know wether the file was obtained from a "drop" or from a GetFile dialog
  126.     if, for instance, you have options based on keys pressed when "dropped," but not when 
  127.     obtained from a dialog.
  128.     
  129.     You will receive one of these messages for each batch of files to be processed,
  130.     before you are told to do any processing.
  131.     
  132.     In ModuleDataRec, theFile is meaningless during this message.
  133.     
  134.     Return TRUE if everything you did as a result of this message was OK.
  135.     Returning FALSE causes File Dropper to send you an eQuitting message and quit.
  136.     
  137. eValidateFile
  138.     This asks you if the file specified in the theFile parameter of the ModuleDataRec record
  139.     is valid for you to work on.  I.E. should eProcessFile be sent?  Return TRUE if you want
  140.     to process it, otherwise return FALSE.
  141.     
  142. eProcessFile
  143.     This tells you to do your thing.  You get this message for each file in the batch.  The
  144.     ModuleDataRec will contain a pointer to the FSSpec for the file that you are to process
  145.     in the theFile parameter.
  146.     
  147.     If you return TRUE and there are any more files to process, you will be sent the next
  148.     file in the batch.  If you return FALSE, no more files will be sent to you for the
  149.     current batch.
  150.  
  151. eUserCancelled
  152.     This tells you that the user clicked Cancel in the status dialog while a file was being
  153.     processed.  The ModuleDataRec will contain a pointer to the FSSpec for the file that
  154.     was being processed in the theFile parameter.  Since File Dropper handles the status 
  155.     dialog only when you call SetStatusPercentage, you will get this message while in a
  156.     call to SetStatusPercentage, thus your ModuleMain must be reentrant with respect to the
  157.     eUserCancelled case.
  158.     
  159.     If you return TRUE, you will get an eDispose message, followed by an eQuitting message, 
  160.     then File Dropper will ExitToShell.  Returning FALSE causes File Dropper to act as if 
  161.     the Cancel button was not pressed.  I suggest you always return TRUE unless you have a 
  162.     really good reason not to, like you are keeping track of the fact that the user cancelled
  163.     and will return FALSE from the next eProcessFile.
  164.  
  165. eDispose
  166.     This tells you that the batch is finished.  This balances out the eAEInitialize or 
  167.     eSFInitialize messages.  It gives you a chance to clean up any data structures you
  168.     set up there.
  169.     
  170.     Return FALSE if you want File Dropper to send you an eQuitting message and quit.  
  171.     Return TRUE if you want File Dropper to keep running.
  172.     
  173.     In ModuleDataRec, theFile is meaningless.
  174.  
  175. eQuitting
  176.     This tells you that the application is about to quit.  If you need to save or flush anything,
  177.     this is the time to do it.
  178.     
  179.     The return value is ignored for this call.
  180.     
  181.     In ModuleDataRec, theFile is meaningless.
  182.  
  183. eIdle
  184.     You get one of these for each NULL event File Dropper gets.  You won't get one while you're
  185.     processing a file.
  186.  
  187. eDoAboutBox
  188.     If you return TRUE from this message, I will handle the about box by reading from the STR#
  189.     number 129.  I will read all strings starting with number 1 in that resource and display
  190.     them in the about box.  Only up to about 6 strings will actually fit in the about box. 
  191.     
  192.     If you return FALSE from the eDoAboutBox message, I will assume that you handled the about
  193.     box and do nothing.
  194.     
  195.  
  196. In summary:
  197.  
  198. eStartup
  199.     REPEAT AS LONG AS USER SELECTS THINGS FROM THE GET FILE DIALOG
  200.         eSFInitialize
  201.             REPEAT FOR EACH FILE
  202.                 eValidateFile
  203.                 eProcessFile    (if validation succeeded)
  204.             END REPEAT
  205.         eDispose
  206.         eIdle (until the user selects Open, Quit, or more files get dropped on)
  207.     END REPEAT*
  208. eQuitting
  209.  
  210. * You can make it so that File Dropper quits after the first 
  211.   selection/processing of a file.  See the section on eDispose.
  212.  
  213. -OR-
  214.  
  215. eStartup
  216.     eAEInitialize
  217.         REPEAT FOR EACH FILE
  218.             eValidateFile
  219.             eProcessFile    (if validation succeeded)
  220.         END REPEAT
  221.     eDispose
  222.     eIdle (until the user selects Open, Quit, or more files get dropped on)
  223. eQuitting†
  224.  
  225. † You can make it so that File Dropper stays open until the user actually 
  226.   selects Quit from the File menu or a 'quit' AppleEvent comes in.  See
  227.   the section on eDispose.
  228.  
  229.  
  230.  
  231.                                 About The Guy Who Wrote It
  232.                                     
  233. This was written by me, Troy Anderson, after a comment from a user of Marker that wanted source
  234. so he could do something else with the files that were dropped on the application.  This allows
  235. you to create little utility applications that do fun things.  If you really like this, and you
  236. write software, send me a copy of it.  Thanks.
  237.  
  238. Internet:        tla@CRL.com
  239. Compuserve:        70410,1407
  240. America Online: Troy A1
  241. US Mail:        Troy Anderson
  242.                 5550 East Roadrunner Road
  243.                 Paradise Valley, AZ  85253
  244.             
  245.                                 
  246.                                 I Want The Source Code!
  247.                                 
  248. If you want the source code (10 commented source files) including AppleEvent sending and receiving,
  249. handling, file manipulation, Standard file customization, finder-like status bar, and the warp
  250. stars about box effect, send me a U.S. check for $35 and a self addressed envelope that will hold
  251. a disk or your Compuserve or America Online address or send $30 and your internet address and I'll
  252. send you the latest version of the source code including at least everything mentioned in this
  253. exceedingly long sentence.  See paragraph three in the Legal Stuff section for what you can do
  254. once you have the souce code, besides reading it.
  255.  
  256.  
  257.                                     Legal Stuff
  258.                                     
  259. If you like it, let me know.  If you want to pay for it, send me money.  If there are bugs, tell
  260. me, I may actually fix them.  Every effort has been made to ensure that this software
  261. works as specified, but it has no warranties, expressed or implied, as to its usefulness, 
  262. stability, or functionalty.  Use this software at your own risk. 
  263.  
  264. You may use and distribute applications made with File Dropper at no charge, but you may not
  265. sell them, or collect money for their distribution (normal disk duplication fees excepted).  
  266. Anyone wishing to distribute an application using File Dropper along with any commercial or 
  267. shareware software package may do so only with my express written consent.
  268.  
  269. If you receive the source code to File Dropper, you may modify it and use it in your own projects
  270. and distribute them as long as they are free of any charge and my name is displayed in the About
  271. Box or other equally accessable place.  If the application you are distributing is a File Dropper
  272. type application, you must either leave the "About YourAppName..." menu item and functionality in 
  273. place, although you can change the menu item's name to be more appropriate, or give me credit in
  274. your custom about box, including "This application is based on the File Dropper by Troy Anderson"
  275. and "File Dropper © 1993 Troy Anderson".